Integration Guide

This guide explains how to integrate your store with the Giftme MiniStore web view bridge, allowing your customers to make purchases using Giftme payment methods.

Overview

The Giftme MiniStore web view bridge integration consists of three main steps:

1. Authentication - Authenticate your MiniStore to access Giftme's platform
2. Order Tokenization - Create a token representing your order details
3. Payment Processing - Use the bridge to process payments with Giftme

Integration Steps

1. Authentication via Web View Bridge

To authenticate your MiniStore and get user information:

In your frontend:

• You'll initiate the authenticate bridge call with your MiniStore ID and mode
• The bridge will handle the authentication process in the Giftme web view
• When successful, your callback URL will receive the authentication token

Your server-side code to verify user information:

<?php
// Get the auth token from the callback
$authToken = $_GET['token'] ?? '';

// Make a request to Giftme API to get user info
$ch = curl_init('https://api.giftme.com/api/ministore/user');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $authToken
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode !== 200) {
    // Handle error
    echo "Failed to get user information";
    exit;
}

$userData = json_decode($response, true);
// User data contains: id, name, email, phone

2. Order Tokenization

When a customer is ready to check out, tokenize the order on your server:

<?php
// Server-side code to tokenize order
function tokenizeOrder($orderData) {
    $ministoreId = 'YOUR_MINISTORE_ID';
    $ministoreSecret = 'YOUR_MINISTORE_SECRET';

    $ch = curl_init('https://api.giftme.com/api/order/tokenize');
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($orderData));
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Content-Type: application/json',
        'X-MiniStore-ID: ' . $ministoreId,
        'X-MiniStore-Secret: ' . $ministoreSecret
    ]);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($httpCode !== 200) {
        // Handle error
        return ['error' => 'Failed to tokenize order'];
    }

    return json_decode($response, true);
}

// Example usage
$orderData = [
    'amount' => 50.00,
    'currency' => 'JMD',
    'external_reference' => 'ORDER-' . uniqid(),
    'notes' => 'Purchase of Product XYZ',
    'mode' => 'sandbox' // Use 'live' for production
];

$result = tokenizeOrder($orderData);
$orderToken = $result['order_token'] ?? null;

// Return order token to the front-end
echo json_encode(['order_token' => $orderToken]);

3. Payment Processing via Web View Bridge

Once you have the order token, your front-end will:

• Initiate the processPayment bridge call with the order token
• The bridge will open the Giftme payment interface
• The customer will select a payment method and complete payment
• Your callback URL will be notified of the payment result

4. Handling Payment Callbacks

Set up a callback endpoint to process the result when payment completes:

<?php
// Payment callback handler
$callbackData = $_GET; // Or $_POST depending on how Giftme sends callbacks

if (isset($callbackData['success']) && $callbackData['success'] === true) {
    // Payment was successful
    $transactionId = $callbackData['transaction_id'] ?? '';
    $externalReference = $callbackData['external_reference'] ?? '';

    // Update your order status
    updateOrderStatus($externalReference, 'paid');

    // Redirect or show confirmation
    header('Location: /order/confirmation?ref=' . $externalReference);
    exit;
} else {
    // Payment failed or was canceled
    $errorMessage = $callbackData['error'] ?? 'Payment failed';

    // Redirect or show error
    header('Location: /order/failed?error=' . urlencode($errorMessage));
    exit;
}

function updateOrderStatus($externalReference, $status) {
    // Your code to update the order status in your database
    // Example:
    // $db->query("UPDATE orders SET status = ? WHERE reference = ?", [$status, $externalReference]);
}

5. Webhook Processing

Set up a webhook endpoint to receive server-to-server payment notifications:

<?php
// Webhook handler
$webhookData = json_decode(file_get_contents('php://input'), true);
$signature = $_SERVER['HTTP_X_SIGNATURE'] ?? '';
$ministoreSecret = 'YOUR_MINISTORE_SECRET';

$calculatedSignature = hash_hmac('sha256', json_encode($webhookData), $ministoreSecret);

if ($signature !== $calculatedSignature) {
    http_response_code(401);
    echo 'Invalid signature';
    exit;
}

// Process the webhook data
$transactionId = $webhookData['transaction_id'] ?? '';
$externalReference = $webhookData['external_reference'] ?? '';
$status = $webhookData['status'] ?? '';

// Log the webhook
error_log('Giftme webhook received: ' . json_encode($webhookData));

// Update order status in your system
if ($status === 'completed') {
    // Payment was successful
    updateOrderStatus($externalReference, 'paid');

    // Additional business logic
    // e.g., send confirmation email, update inventory, etc.
}

// Acknowledge receipt of webhook
http_response_code(200);
echo 'Webhook received';

Bridge Calls Reference

The Giftme web view bridge supports these main calls:

Call	Description
authenticate	Opens the Giftme authentication flow and returns a token
processPayment	Opens the Giftme payment interface for the provided order token

Testing

1. Start with mode: 'sandbox' to test your integration
2. Verify both callback and webhook processing works correctly
3. Test different payment flows and error conditions

Going Live

When you're ready to go live:

1. Switch to mode: 'live' in your tokenization and bridge calls
2. Update your API credentials to production values
3. Ensure your callback URL and webhook URL are properly configured